)

Recreation of #90314

---

## Summary
- Fix `--debug-build-paths` pages normalization in Turbopack so
`pages/<name>/index.tsx` maps to `/<name>` (matching JS
`getPageFromPath()` behavior).
- Handle index page edge case: `/index.tsx -> /`.
- Keep regression coverage in
`test/production/debug-build-path/debug-build-paths.test.ts` with a
generic fixture `pages/with-index/index.tsx`.

## Current Behavior Reference
- CI run (before this fix) that failed as expected for this bug:
-
https://github.com/vercel/next.js/actions/runs/22266469801/job/64413677099?pr=90314#step:35:216

## Root Cause
Rust-side debug-build-path normalization removed file extensions but did
not remove `/index`, producing route keys like `/with-index/index` while
pages route keys are `/with-index`. That mismatch filtered out the page
and caused `PageNotFoundError` during page-data collection.

---------

Co-authored-by: devjiwonchoi <devjiwonchoi@gmail.com>

### What?

Add GitHub SSH authentication guidance to `AGENTS.md` for
user-configured SSH agents and key providers.

### Why?

Remote operations can fail when an SSH agent or key provider is
unavailable or locked. The guidance prevents unrequested authentication
workarounds and directs agents to involve the user when signing fails.

### How?

Document recognized SSH signing failure symptoms, the required
stop-and-ask behavior, and a lightweight preflight recommendation before
force-pushes or stack rebases that may hydrate partial-clone objects.

### Verification

- `pnpm prettier --with-node-modules --ignore-path .prettierignore
--write AGENTS.md`
- `git diff --cached --check`
- `pnpm build-all`

<!-- NEXT_JS_LLM_PR -->

### What?

Deprecate undocumented custom-server methods exposed by `next()` while
preserving their runtime behavior.

- Add TypeScript deprecation annotations and one-time runtime warnings
for `setAssetPrefix()`, logging helpers, `revalidate()`, and legacy
`render*` helpers.
- Extend custom-server tests to cover warnings and warning
deduplication.
- Move unrelated test fixtures away from deprecated custom-server calls.

### Why?

These methods are not part of the documented custom-server API, but
existing applications may still rely on them. Warning-only deprecation
gives users migration guidance without introducing a breaking runtime
change.

### How?

Warnings are emitted only through `NextCustomServer`, so framework-owned
`NextServer` usage remains quiet. The warning text points `render*`
callers toward `app.getRequestHandler()`, `setAssetPrefix()` callers
toward configuration, and logging and revalidation callers toward
supported application APIs.

The tests retain compatibility assertions for existing behavior, add
deliberate invocations for previously uncovered methods, verify
once-per-process warning deduplication, and remove incidental warning
sources in unrelated fixtures.

<!-- NEXT_JS_LLM_PR -->

### What?

Add focused production adapter coverage for configured `cacheHandler`
and `cacheHandlers` module graphs in Node `output.assets`, including
transitive helper dependencies and Turbopack `assetsHashes` assertions.

### Why?

Adapter deployments dynamically load configured cache handlers at
runtime. This coverage demonstrates that Node adapter outputs currently
omit those handler files and their transitive dependencies.

### How?

Add an App Router Cache Components fixture using `adapterPath`, both
cache-handler APIs, and a `use cache: remote` route. Its adapter writes
`onBuildComplete` context to disk and the test inspects Node outputs for
each handler and uniquely named helper.

### Verification

- `NEXT_TEST_PREFER_OFFLINE=1 pnpm --filter=next build`
- Expected failure: `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-start-turbo
test/production/app-dir/adapter-cache-handlers/adapter-cache-handlers.test.ts`
(no Node output contains all four handler assets)
- Expected failure: `NEXT_TEST_PREFER_OFFLINE=1 pnpm test-start-webpack
test/production/app-dir/adapter-cache-handlers/adapter-cache-handlers.test.ts`
(same adapter handoff gap)
- `git diff canary --check`
- Not run continuously: `pnpm --filter=next dev` (`EMFILE: too many open
files` occurred after startup in the local watcher)

<!-- NEXT_JS_LLM_PR -->

---------

Co-authored-by: Niklas Mischkulnig <4586894+mischnic@users.noreply.github.com>

In #93801, we'll be adding 4 new stages. `StagedRenderingController`
already contains a lot of duplication around advancing stages, and i
want to avoid adding to that, so this PR does some cleanup.

Previously, for a stage, we had
- `resolve<name>Stage` - triggers listener callbacks and resolves the
promise for the stage
- `<name>StageListeners` - added via `onStage`, triggered when advancing
to the stage but before resolving the promise
- `<name>StagePromise` - resolved when we enter the stage (or rejected
on abort/abandon)
- sometimes, `<name>EndTime`

these behaviors are all now packaged up into `StageTrigger`, which can
be "fired" (when advancing to a stage) or "cancelled" (when
aborting/abandoning) and tracks the time.

In addition, we now have `RENDER_STAGE_ADVANCE_ORDER`, an array that
defines the order in which advanceable stages (i.e. excluding
Before/Abandoned) should happen. We can loop through this to advance
stages without relying on a huge switch statement with fallthroughs.
Re-working the logic into this shape will be handy in the future, when
we want each route param to have its own stage, and the set of stages is
no longer statically known.

### What?

Adds a `## Behavior` → `### Cache Components` section to the API
reference pages for `usePathname`, `useSelectedLayoutSegment`, and
`useSelectedLayoutSegments`.

### Why?

When `cacheComponents` is enabled, these hooks suspend during
prerendering on routes that have dynamic params not covered by
`generateStaticParams`. This was previously only hinted at with a
one-line note on `usePathname` and undocumented on the layout segment
hooks, even though they share the same behavior.

### How?

- `usePathname`: replaced the terse one-line note with a `## Behavior` →
`### Cache Components` section explaining when it resolves on the server
vs. suspends. Also added a link to the [Preventing flash before
hydration](/docs/app/guides/preventing-flash-before-hydration) guide in
the existing rewrite-mismatch example, and cleaned up a stray em dash.
- `useSelectedLayoutSegment`: added the same `### Cache Components`
section.
- `useSelectedLayoutSegments`: added the same `### Cache Components`
section.

The rewrite/Proxy hydration-mismatch gotcha is intentionally not
duplicated to the layout segment pages — those hooks derive their value
from the routing tree, not the URL pathname, so rewrites don't produce
the same mismatch.

Documents existing behavior only — no API surface changes.

Mitigates a regression introduced in
#94044. We switched from prerender
to render + cutting of chunks that are emitted after abort. This works
well for the abort we trigger to finish prerendering, because we ensure
that everything that was going to flush some output already did so
before we abort.
However, when Sync IO causes an abrupt abort in the middle of rendering,
we also have to stop collecting output immediately (because e.g. async
iterables are errored ~immediately, without `scheduleWork`), which means
that partially-finished chunks may get omitted from the output.
Essentially, when Sync IO happens, we might lose more content that we
would've if we did a halt.

In the the pages in the test suite added here, the root chunk (row 0)
ends up being blocked. Before the fix introduced in this PR, this bad
RSC payload would then flow into `collect-segment-data.ts` which
attempts to deserialize it and hangs in an unexpected way (because with
a halt, the root chunk was always there).

I've also had to add a weird workaround to the streaming prerender
codepaths -- it seems like in --debug-prerender, the stale time iterable
keeps the stream open even after an abort, and we need to close it
manually (which seems like a react bug). See NAR-810

<!-- Thanks for opening a PR! Your contribution is much appreciated.
To make sure your PR is handled as smoothly as possible we request that
you follow the checklist sections below.
Choose the right checklist for the change(s) that you're making:

## For Contributors

### Improving Documentation

- Run `pnpm prettier-fix` to fix formatting issues before opening the
PR.
- Read the Docs Contribution Guide to ensure your contribution follows
the docs guidelines:
https://nextjs.org/docs/community/contribution-guide

### Fixing a bug

- Related issues linked using `fixes #number`
- Tests added. See:
https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Adding a feature

- Implements an existing feature request or RFC. Make sure the feature
request has been accepted for implementation before opening a PR. (A
discussion must be opened, see
https://github.com/vercel/next.js/discussions/new?category=ideas)
- Related issues/discussions are linked using `fixes #number`
- e2e tests added
(https://github.com/vercel/next.js/blob/canary/contributing/core/testing.md#writing-tests-for-nextjs)
- Documentation added
- Telemetry added. In case of a feature if it's used or not.
- Errors have a helpful link attached, see
https://github.com/vercel/next.js/blob/canary/contributing.md

### Signed commits

- This repository requires verified commit signatures on protected
branches.
- If this pull request is blocked for unsigned commits, re-sign the
commits and force-push the branch.
- A `Signed-off-by` line in the commit message is not enough.


## For Maintainers

- Minimal description (aim for explaining to someone not on the team to
understand the PR)
- When linking to a Slack thread, you might want to share details of the
conclusion
- Link both the Linear (Fixes NEXT-xxx) and the GitHub issues
- Add review comments if necessary to explain to the reviewer the logic
behind a change

### What?

### Why?

### How?

Closes NEXT-
Fixes #

-->

While working on #93801 , i added some stricter checks about early/late
stages. In particular, if we're in the `Before`stage (generally, while
running `createComponentTree`), we can't know if we're supposed to use
early or late stages. Making this stricter revealed that
`createServerPathnameForMetadata` was accidentally always using the late
stage because it runs in `Before`. Instead, it should check
`isRuntimePrefetchable` like we do for `params` and `searchParams`, so
i'm refactoring it to do that here.